pretty-format

What is pretty-format?

The pretty-format npm package is a JavaScript library that allows you to serialize any JavaScript value into a string with a human-readable format. It is particularly useful for snapshot testing, where you want to compare the expected and actual output of your test cases.

What are pretty-format's main functionalities?

Pretty-printing of basic JavaScript types

This feature allows you to convert basic JavaScript types like objects, arrays, strings, numbers, etc., into a nicely formatted string.

const prettyFormat = require('pretty-format');
const value = { foo: 'bar', baz: 42 };
console.log(prettyFormat(value));

Customizing output with plugins

pretty-format supports plugins that can be used to customize the output for specific types of values, such as React elements.

const prettyFormat = require('pretty-format');
const ReactElementPlugin = require('pretty-format/plugins/ReactElement');
const reactElement = <div>Hello World</div>;
console.log(prettyFormat(reactElement, { plugins: [ReactElementPlugin] }));

Minimizing diff output

By using pretty-format in combination with a diffing library like jest-diff, you can minimize the output of diffs to make them easier to read and understand.

const prettyFormat = require('pretty-format');
const diff = require('jest-diff');
const oldValue = { a: 'old', b: 'values' };
const newValue = { a: 'new', b: 'values' };
const difference = diff(prettyFormat(oldValue), prettyFormat(newValue));
console.log(difference);

Other packages similar to pretty-format

chalk

Chalk is a popular npm package for styling terminal strings. While it doesn't serialize objects, it can be used in conjunction with pretty-format to colorize the output, enhancing readability.

util

Util is a core Node.js module that provides a method called 'inspect' for printing objects in a readable format. It is similar to pretty-format but is built into Node.js and does not support plugins.

js-beautify

js-beautify is an npm package that can format HTML, CSS, and JavaScript code. It is more focused on formatting code rather than serializing arbitrary JavaScript values like pretty-format.

README

pretty-format

Stringify any JavaScript value.

• Supports all built-in JavaScript types
• Blazingly fast (similar performance to v8's JSON.stringify and significantly faster than Node's util.format)
• Plugin system for extending with custom types (i.e. ReactTestComponent)

Installation

$ yarn add pretty-format

Usage

const prettyFormat = require('pretty-format');

var obj = { property: {} };
obj.circularReference = obj;
obj[Symbol('foo')] = 'foo';
obj.map = new Map();
obj.map.set('prop', 'value');
obj.array = [1, NaN, Infinity];

console.log(prettyFormat(obj));

Result:

Object {
  "property": Object {},
  "circularReference": [Circular],
  "map": Map {
    "prop" => "value"
  },
  "array": Array [
    1,
    NaN,
    Infinity
  ],
  Symbol(foo): "foo"
}

Type Support

Object, Array, ArrayBuffer, DataView, Float32Array, Float64Array, Int8Array, Int16Array, Int32Array, Uint8Array, Uint8ClampedArray, Uint16Array, Uint32Array, arguments, Boolean, Date, Error, Function, Infinity, Map, NaN, null, Number, RegExp, Set, String, Symbol, undefined, WeakMap, WeakSet

API

console.log(prettyFormat(object));
console.log(prettyFormat(object, options));

Options:

• callToJSON
  Type: boolean, default: true
  Call toJSON() on passed object.
• indent
  Type: number, default: 2
  Number of spaces for indentation.
• maxDepth
  Type: number, default: Infinity
  Print only this number of levels.
• min
  Type: boolean, default: false
  Print without whitespace.
• plugins
  Type: array, default: []
  Plugins (see the next section).
• printFunctionName
  Type: boolean, default: true
  Print function names or just [Function].
• escapeRegex
  Type: boolean, default: false
  Escape special characters in regular expressions.
• highlight
  Type: boolean, default: false
  Highlight syntax for terminal (works only with ReactTestComponent and ReactElement plugins.
• theme
  Type: object, default: {tag: 'cyan', content: 'reset'...}
  Syntax highlight theme.
  Uses ansi-styles colors + reset for no color.
  Available types: tag, content, prop and value.

Plugins

Pretty format also supports adding plugins:

const fooPlugin = {
  test(val) {
    return val && val.hasOwnProperty('foo');
  },
  print(val, print, indent) {
    return 'Foo: ' + print(val.foo);
  }
};

const obj = {foo: {bar: {}}};

prettyFormat(obj, {
  plugins: [fooPlugin]
});
// Foo: Object {
//   "bar": Object {}
// }

ReactTestComponent and ReactElement plugins

const prettyFormat = require('pretty-format');
const reactTestPlugin = require('pretty-format/build/plugins/ReactTestComponent');
const reactElementPlugin = require('pretty-format/build/plugins/ReactElement');

const React = require('react');
const renderer = require('react-test-renderer');

const element = React.createElement('h1', null, 'Hello World');

prettyFormat(renderer.create(element).toJSON(), {
  plugins: [reactTestPlugin, reactElementPlugin]
});
// <h1>
//   Hello World
// </h1>

Changelog

jest 19.0.0

• Breaking Change: Added a version for snapshots.
• Breaking Change: Removed the mocksPattern configuration option, it never worked correctly.
• Breaking Change: Renamed testPathDirs to roots to avoid confusion when configuring Jest.
• Breaking Change: Updated printing of React elements to cause fewer changes when props change.
• Breaking Change: Updated snapshot format to properly escape data.
• Fixed --color to be recognized correctly again.
• Fixed babel-plugin-jest-hoist to work properly with type annotations in tests.
• Fixed behavior for console.log calls and fixed a memory leak (#2539).
• Fixed cache directory path for Jest to avoid ENAMETOOLONG errors.
• Fixed change events to be emitted in jest-haste-map's watch mode. This fixes issues with Jest's new watch mode and react-native-packager.
• Fixed cli arguments to be used when loading the config from file, they were previously ignored.
• Fixed Jest to load json files that include a BOM.
• Fixed Jest to throw errors instead of ignoring invalid cli options.
• Fixed mocking behavior for virtual modules.
• Fixed mocking behavior with transitive dependencies.
• Fixed support for asymmetric matchers in toMatchObject.
• Fixed test interruption and --bail behavior.
• Fixed watch mode to clean up worker processes when a test run gets interrupted.
• Fixed whitespace to be highlighted in snapshots and assertion errors.
• Improved babel-jest plugin: babel is loaded lazily, istanbul comments are only added when coverage is used.
• Improved error for invalid transform config.
• Improved moduleNameMapper to not overwrite mocks when many patterns map to the same file.
• Improved printing of skipped tests in verbose mode.
• Improved resolution code in jest-resolve.
• Improved to only show patch marks in assertion errors when the comparison results in large objects.
• New --collectCoverageFrom cli argument.
• New --coverageDirectory cli argument.
• New expect.addSnapshotSerializer to add custom snapshot serializers for tests.
• New jest.spyOn.
• New testMatch configuration option that accepts glob patterns.
• New eslint-plugin-jest with no-disabled-tests, no-focuses-tests and no-identical-title rules and default configuration and globals.
• New expect.stringContaining asymmetric matcher.
• New feature to make manual mocks with nested folders work. For example __mocks__/react-native/Library/Text.js will now work as expected.
• New feature to re-run tests through the notification when using --notify.
• New jest-phabricator package to integrate Jest code coverage in phabriactor.
• New jest-validate package to improve configuration errors, help with suggestions of correct configuration and to be adopted in other libraries.
• New pretty-printing for asymmetric matchers.
• New RSS feed for Jest's blog.
• New way to provide a reducer to extract haste module ids.
• New website, new documentation, new color scheme and new homepage.
• Rewritten watch mode for instant feedback, better code quality and to build new features on top of it (#2362).